From 2c3d9333496aa235ec6789bc6bf4f5c5396c6f91 Mon Sep 17 00:00:00 2001 From: Mattes D Date: Fri, 27 Nov 2015 09:29:13 +0100 Subject: Added more details to the cubeset format documentation. --- docs/Cubeset file format.html | 37 +++++++++++++++++++++++++++++++++---- src/Generating/PrefabPiecePool.cpp | 4 ++-- 2 files changed, 35 insertions(+), 6 deletions(-) diff --git a/docs/Cubeset file format.html b/docs/Cubeset file format.html index 916d723af..da4fe4e88 100644 --- a/docs/Cubeset file format.html +++ b/docs/Cubeset file format.html @@ -33,7 +33,7 @@ With Lua, we could store any metadata for the prefabs, any additional informatio

Detailed description of the format

-The Cubeset file has a .cubeset extension. Internally it is a Lua source file that provides a global value, Cubeset, which is a table containing the structured data. The loader checks the file's first 4 KiB to see if there is a "CubesetFormatVersion =" string in it, and if it is, the file is considered a Cubeset file and further loading is attempted. It is therefore crucial that tools producing this file format include this string as early as possible in the file.

+The Cubeset file has a .cubeset extension. Internally it is a Lua source file that provides a global value, Cubeset, which is a table containing the structured data. The loader checks the file's first 8 KiB to see if there is a "CubesetFormatVersion =" string in it (note the space between the word and the equals-sign), and if it is, the file is considered a Cubeset file and further loading is attempted. It is therefore crucial that tools producing this file format include this string as early as possible in the file.

The top-level Cubeset table must contain at least two sub-tables: Metadata and Pieces. The Metadata table contains the metadata relevant to the entire set of prefabs in the file, the Pieces table contains the definitions and metadata for the individual prefabs. It is advised to make the Metadata table the first one, because it contains the signature used to identify the file ("CubesetFormatVersion ="). Apart from these two subtables the server ignores everything else.

@@ -42,11 +42,31 @@ The top-level Cubeset table must contain at least two sub-tables: Metadata and P The Cubeset.Metadata table is used to store metadata for the entire set of prefabs, and also for the format and version identification. It is a regular dictionary-style Lua table; the following elements are recognized: - + + +
NameTypeContent
CubesetFormatVersionnumberThis is the format identification and at the same time it specifies the version of the file. Currently the file version is 1.
CubesetFormatVersionnumberThis is the format identification and at the same time it specifies the version of the file. Currently the file version is 1. Note that Cuberite checks the presence of the string "CubesetFormatVersion =", including the space between the word and the equals-sign, within the first 8 KiB of the file.
ExportDatestringThe date when this file was exported, in the ISO format ("2015-06-16 13:34:03"). Inserted by GalExport for versioning purposes. Ignored elsewhere.
ExternalSchematicbooleanFlag inserted by GalExport to indicate that the individual prefabs are stored in separate .schematic files. Ignored elsewhere.
IntendedUsestringString identifying the generator part that the cubeset file is intended for. The server logs a warning when loading a cubeset file without an IntendedUse metadata; individual generators log a warning if a wrong IntendedUse is detected in a file they are asked to use.
+

+

Additional values are recognized by the specific generator (which is indicated by the IntendedUse value):

+ + + + + + + + + + + + + + + + +
Generator (IntendedUse)NameTypeContentNotes
Village / PieceStructures / TreesAllowedBiomesstringComma-separated list of biomesThe generator only generates the structure / village / tree in the specified biomes. If empty, all biomes are eligible.
VillageMaxDensitynumberMaximum density (0 - 100) at which the connectors are populated.The village generator picks a density between Min and Max, and then only that many percent of the free connectors are actually attempted. This eventually reduces the number of houses to make the village look more "roomy".
MinDensitynumberMinimum density (0 - 100) at which the connectors are populated.
VillageRoadBlockTypenumberThe block type used in the village for regular roads on the solid surfaceThe generator replaces the top terrain block with the specified block type and meta to form the roads. The generator can distinguish when it's replacing water and when it's replacing regular terrain, allowing the villages to include "bridges" as their roads.
VillageRoadBlockMetanumberThe block meta used in the village for regular roads on the solid surface
VillageWaterRoadBlockTypenumberThe block type used in the village for roads on the surface of water
VillageWaterRoadBlockMetanumberThe block meta used in the village for roads on the surface of water
PieceStructuresGridSizeXnumberSize, in blocks, of the seed gridThe generator starts each generated structure in a "seed", these two parameters control the (average) distances between two adjacent seeds.
GridSizeZnumber
MaxOffsetXnumberMaximum offset, in blocks, of the seed from the grid's centerThe generator starts each generated structure in a "seed", these two parameters control the maximum distance of the seed from the regular grid (specified by GridSizeX and GridSizeZ). When zero, the structures are generated exactly on a rectangular grid. Recommended value is about half of the grid's size.
MaxOffsetZnumber
MaxStructureSizeXnumberSize, in blocks, of the bounding box for a single structure.The generator will not connect any prefab to the rest of the structure if it crosses the bounding box.
MaxStructureSizeZnumber
MaxDepthnumberMaximum depth of the generated piece treeThe maximum number of connectors, away from the starting piece
SeedOffsetnumberNumber that is added to world's seed for this generatorEach cubeset file should have a different seed offset, otherwise it runs the risk of its structures being generated directly over other cubeset file's that the server admin has enabled. Since the seed is used for placement, if two cubeset files share the same seed, they will share the structure placement as well.
-We expect that the set of values recognized by the server will grow when the format is used for some time. All values are optional, except for the CubesetFormatVersion value which is strictly checked by the server.

Individual piece

@@ -112,6 +132,15 @@ Cubeset = Metadata = { CubesetFormatVersion = 1, + IntendedUse = "PieceStructures", + GridSizeX = 128, + GridSizeZ = 128, + MaxStructureSizeX = 64, + MaxStructureSizeZ = 64, + MaxOffsetX = 16, + MaxOffsetZ = 16, + MaxDepth = 4, + SeedOffset = 13, }, Pieces = @@ -288,7 +317,7 @@ Cubeset = }, SchematicFile = "PlainsVillage/20.schematic", }, -- DoublePlantBed - } + } -- Pieces } diff --git a/src/Generating/PrefabPiecePool.cpp b/src/Generating/PrefabPiecePool.cpp index d4235f9dd..e1bb9f684 100644 --- a/src/Generating/PrefabPiecePool.cpp +++ b/src/Generating/PrefabPiecePool.cpp @@ -186,8 +186,8 @@ bool cPrefabPiecePool::LoadFromString(const AString & a_Contents, const AString } } - // Read the first 4 KiB of the file in order to auto-detect format: - auto Header = a_Contents.substr(0, 4096); + // Search the first 8 KiB of the file for the format auto-detection string: + auto Header = a_Contents.substr(0, 8192); if (Header.find("CubesetFormatVersion =") != AString::npos) { return LoadFromCubeset(a_Contents, a_FileName, a_LogWarnings); -- cgit v1.2.3